home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Taifun / Taifun 040 (1987-11-15)(Ossowski, Stefan)(DE)(PD).zip / Taifun 040 (1987-11-15)(Ossowski, Stefan)(DE)(PD).adf / A68k / A68k.Doc < prev    next >
Text File  |  1989-01-18  |  15KB  |  339 lines

  1.     A68k - a freely    distributable assembler    for the    Amiga
  2.  
  3.             by Charlie Gibbs
  4.  
  5.              with special thanks to
  6.         Brian R. Anderson and Jeff Lydiatt
  7.  
  8.         (Version 1.02 -    September 9, 1987)
  9.  
  10. Note: This program is NOT Public Domain.  Permission is    given to freely
  11. distribute this    program    provided no fee    is charged, and    this
  12. documentation file is included with the    program.
  13.  
  14.      This assembler is based on    Brian R. Anderson's 68000 cross-assembler
  15. published in Dr. Dobb's Journal, April through June 1986.  I have converted
  16. it to produce AmigaDOS-format object modules, and have made many enhancements,
  17. such as    macros and include files.
  18.  
  19.      My    first step was to convert the original Modula-2    code into C.
  20. I did this for two reasons.  First, I had access to a C    compiler, but
  21. not a Modula-2 compiler.  Second, I like C better anyway.
  22.  
  23.      The executable code generator code    (GetObjectCode and MergeModes) is
  24. essentially the    same as    in the original    article, aside from its    translation
  25. into C.     I have    almost completely rewritten the    remainder of the code,
  26. however, in order to remove restrictions, add enhancements, and    adapt it to
  27. the AmigaDOS environment.  Since the only reference book available to me
  28. was the    AmigaDOS Developer's Manual (Bantam, February 1986), the assembler
  29. and the    remainder of this document work    in terms of that book.
  30.  
  31.  
  32. RESTRICTIONS
  33.  
  34.      Let's get these out of the way first.  There are a few things that I
  35. have not yet implemented, and some outright bugs that would take too long
  36. to correct for this version.
  37.  
  38.       o    The verification file (-v) option is not supported.  Diagnostic
  39.     messages always    appear on the console.    They also appear in the
  40.     listing    file, however (see extensions below).
  41.  
  42.       o    The file names in the include directory    list (-i) must be separated
  43.     by commas.  The    list may not be    enclosed in quotes.
  44.  
  45.       o    Labels assigned    by EQUR    and REG    directives are case-sensitive.
  46.  
  47.       o    The following directives are not supported, and    will be    flagged    as
  48.     invalid    op-codes:
  49.  
  50.         RORG
  51.         OFFSET
  52.         NOPAGE
  53.         LLEN
  54.         PLEN
  55.         NOOBJ
  56.         FAIL
  57.         FORMAT
  58.         NOFORMAT
  59.         MASK2
  60.  
  61.     I feel that NOPAGE, LLEN, and PLEN should not be defined within    a
  62.     source module.    It doesn't make sense to me to have to change your
  63.     program    just because you want to print your listings on    different
  64.     paper.    The command-line option    "-p" (see below) can be used as a
  65.     replacement for    PLEN.
  66.  
  67.  
  68. EXTENSIONS
  69.  
  70.      Now for the good stuff:
  71.  
  72.       o    Labels can be any length that will fit onto one    source line
  73.     (currently 127 bytes maximum).    Since labels are stored    on the
  74.     heap, the number of labels that    can be processed is limited only
  75.     by available memory, which can be increased by using the "-w"
  76.     option (see below).
  77.  
  78.       o    Since section data and user macro definitions are stored on the
  79.     same heap as the symbol    table (see above), they    too are    limited
  80.     only by    available memory.  (Actually, there is a hard-coded limit
  81.     of 32767 sections, but I doubt anyone will run into that one.)
  82.  
  83.       o    The only values    a label    cannot take are    the register names - the
  84.     assembler can distinguish between the same name    used as    a label,
  85.     instruction name, macro    name, directive, or section name.
  86.  
  87.       o    Section    and user macro names appear in the symbol table    dump, and
  88.     will also be cross-referenced.    Their names can    be the same as any
  89.     label (see above); the assembler can sort them out.
  90.  
  91.       o    Includes and macro calls can be    nested indefinitely, limited only
  92.     by available memory.  The message "Secondary heap overflow -
  93.     assembly terminated" will be displayed if memory is exhausted.
  94.     You can    increase the size of this heap using the -w parameter
  95.     (see below).  Recursive    macros are supported; recursive    includes
  96.     will, of course, result    in a loop that will be broken only when
  97.     the heap overflows.
  98.  
  99.       o    The EVEN directive forces alignment on a word (2-byte) boundary.
  100.     It does    the same thing as CNOP 0,2.
  101.     (This one is left over from the    original code.)
  102.  
  103.       o    Branch (Bcc) instructions to a previously-defined label    will be
  104.     automatically converted    to short form if possible.  This feature is
  105.     not available for forward branches, since in pass 1 the    assembler
  106.     doesn't yet know how far the branch must go.
  107.  
  108.       o    If a MOVEM instruction only specifies one register, it is converted
  109.     to the corresponding MOVE instruction.    Instructions of    the form
  110.     MOVEM D0-D0,label will not be converted, however.
  111.  
  112.       o    ADD, SUB, and MOVE instructions    will be    converted to ADDQ, SUBQ,
  113.     and MOVEQ respectively if possible.  Instructions coded    explicitly
  114.     as (for    example) ADDA or ADDI will not be converted.
  115.  
  116.       o    ADD, CMP, SUB, and MOVE    to an address register are converted to
  117.     ADDA, CMPA, SUBA, and MOVEA respectively, except if an ADD, SUB,
  118.     or MOVE    instruction has    already    been converted to quick    form.
  119.  
  120.       o    ADD, AND, CMP, EOR, OR,    and SUB    of an immediate    value are converted
  121.     to ADDI, ANDI, CMPI, EORI, ORI,    and SUBI respectively (unless the
  122.     address    register or quick conversion above has already been done).
  123.  
  124.       o    If both    operands of a CMP instruction are postincrement    mode, the
  125.     instruction is converted to CMPM.
  126.  
  127.       o    The SECTION directive allows a third parameter.     This can be
  128.     specified as either CHIP or FAST (upper- or lower-case).  If this
  129.     parameter is present, the hunk will be written with the    MEMF_CHIP
  130.     or MEMF_FAST bit set.  This allows you to produce "pre-ATOMized"
  131.     object modules.
  132.  
  133.       o    The synonyms DATA and BSS are accepted for SECTION directives
  134.     starting data or BSS hunks.  A section name is mandatory for
  135.     all non-CODE hunks.
  136.  
  137.       o    The ability to produce Motorola    S-records is retained from the
  138.     original code.    The -s option causes the assembler to produce
  139.     S-format instead of AmigaDOS format.  Relocatable code cannot be
  140.     produced in this format.
  141.  
  142.       o    Error messages include the name    of the source, macro, or include
  143.     module that contains the statement in error, plus the line number
  144.     within the module of the offending line.  If a statement has
  145.     multiple errors, this information appears only on the first
  146.     error message for the statement.
  147.  
  148.  
  149. HOW TO USE IT
  150.  
  151.      The command-line syntax to    run the    assembler is as    follows:
  152.  
  153.     a68k <source file>
  154.         [-e<equate file>]
  155.         [-h<header file>]
  156.         [-i<include dirlist>]
  157.         [-l<listing file>]
  158.         [-o<object file>]
  159.         [-p<page depth>]
  160.         [-d]
  161.         [-s]
  162.         [-w[<primary-heap-size>][,secondary-heap-size]]
  163.         [-x]
  164.  
  165. These options can be given in any order, so if you like    to specify your
  166. switches first,    you can.  Option values, if any, must immediately follow
  167. the keyword with no intervening    spaces.
  168.  
  169.      If    the -o keyword is omitted, the object file will    be given a default
  170. name.  It is created by    replacing all characters after the last    period in
  171. the source file    name by    "o".  For example, if the source file name is
  172. "myprog.asm", the object file name defaults to "myprog.o".  A source name
  173. of "my.new.prog.asm" produces a default object file name of "my.new.prog.o".
  174. If the source file name    does not contain a period, ".o" is appended to it
  175. to produce the default object file name.
  176.  
  177.      The default value for the listing file name is arrived at in the same
  178. way as the object file name, except that ".lst" is appended instead of ".o".
  179. If you don't specify this parameter, no listing file will be produced.
  180. If you specify -x (see below), -l (with    the default name) is assumed,
  181. although you can still use this    parameter if you wish.
  182.  
  183.      The default value for the equate file name    is arrived at in the same
  184. way as the object file name, except that ".equ" is appended instead of ".o".
  185.  
  186.      The include directory list    is a list of directory names separated by
  187. commas.     No embedded blanks are    allowed.  For example, the specification
  188.     -imylib,df1:another.lib
  189. will cause include files to be searched    for first in the current directory,
  190. then in    "mylib", then in "df1:another.lib".
  191.  
  192.      The -d keyword causes symbol table    entries    (hunk_symbol) to be written
  193. to the object module for the use of symbolic debuggers.
  194.  
  195.      The -p keyword causes the page depth to be    set to the specified value.
  196. If omitted, a default of 60 lines (-p60) is assumed.
  197.  
  198.      The -s keyword, if    specified, causes the object file to be    written    in
  199. Motorola S-record format.  If omitted, AmigaDOS    format will be produced.
  200. The default name for an    S-record file has ".s" appended to the source name,
  201. rather than ".o"; this can still be overridden with the -o keyword, though.
  202.  
  203.      The -w keyword specifies the size of the heaps used.  The primary heap
  204. stores the symbol table, user macro text, relocation information, and
  205. cross-reference    information.  The secondary heap stores    information for
  206. nested macro calls and include files.  The primary heap    size defaults to
  207. 32768 bytes, which should be enough for    all but    the largest assemblies.
  208. The secondary heap size    defaults to 1024 bytes,    which should be    enough
  209. unless you use very deeply nested macros and/or    include    files with long
  210. path names.  You can specify either or both parameters.     For example:
  211.     -w40000        secondary heap size remains at 1024 bytes
  212.     -w,2000        primary    heap size remains at 32768 bytes
  213.     -w40000,2000    increases the size of both heaps
  214. If you're really tight for memory, and are assembling small modules, you
  215. can use    this keyword to    shrink the heaps below their default sizes.
  216. At the end of an assembly, a message will be displayed giving the
  217. amount of heap space actually used, in the form    of the -w command
  218. you would have to enter    to allocate the    mininum    heap space.
  219. See below for a    layout of the heaps.
  220.  
  221.      The -x keyword will produce a symbol table    dump, including
  222. cross-reference    information.  If you haven't also specified -l (with
  223. or without a file name), -l with the default file name will be assumed.
  224.  
  225.  
  226.      If    you wish to override the default object    and (optionally) listing
  227. file names, you    can omit the -o    and -l keywords.  The assembler    interprets
  228. the first three    parameters without leading hyphens as the source, object,
  229. and listing file names respectively.  Anything over three file names is    an
  230. error, as is attempting    to respecify a file name with the -o or    -l keywords.
  231.  
  232.  
  233.      The primary heap is built from both ends.    Symbol table entries
  234. (including labels) and macro text are stored during pass 1.  Cross-reference
  235. data is    stored during pass 2.  Relocation information is also stored during
  236. pass 2,    but is cleared at the end of each SECTION.  Since it is    no longer
  237. needed once dumped, the    space is freed for re-use by the next section's
  238. relocation information.     The expression    parser also uses the primary heap
  239. to store its working stacks - this space is freed as soon as an    expression
  240. has been evaluated.
  241.      The fixed portion of each symbol table entry occupies 16 bytes.  The
  242. labels and macro text occupy just enough space to hold their strings
  243. (including the end-of-string delimiter)    - they are all pointed to by fixed
  244. symbol table entries.  Relocation entries occupy 10 bytes each.
  245. Cross-reference    entries    are 12 bytes long - each holds four references to
  246. one symbol.  The expression parser creates temporary entries for terms
  247. (10 bytes each)    and operators (4 bytes each).  Since terms are combined
  248. as soon    as possible, the parser    almost never needs to store the    entire
  249. expression on the heap.
  250.      The diagram below illustrates the layout of the primary heap.  High
  251. memory addresses are at    the top    of the diagram,    while low addresses are
  252. at the bottom.    The names on the left of the diagram are the names of the
  253. pointers to the    various    tables within the heap.
  254.  
  255.     Heap + maxheap ------------->  ___________________________
  256.                       |                  |
  257.                       |      Symbol table          |
  258.     struct SymTab *SymStart     ---> |___________________________|
  259.                       |                  |
  260.                       |      Symbol references      |
  261.     struct Ref *RefStart -------> |___________________________|
  262.                       |                  |
  263.                       |      (unused space)      |
  264.     char *HeapLim --------------> |___________________________|
  265.                       |                  |
  266.                       |      Relocation data      |
  267.     struct RelTab *RelStart    ----> |___________________________|
  268.                       |                  |
  269.                       |      Labels and macro text      |
  270.     char *Heap -----------------> |___________________________|
  271.  
  272.      Note that the pointers are    to various types.  This    makes for
  273. lots of    interesting casts.  (Ain't C fun?)  Since the relocation
  274. data is    cleared    at the end of each section, HeapLim will move up and
  275. down.  The "high-water mark" is stored in char *HighHeap, which is
  276. used solely to produce the memory usage    message    at the end of the
  277. assembly.  Note    that a program may consist of a    section    containing
  278. many relocatable references, followed by a section with    fewer
  279. relocatable references but lots    of symbol references.  In this case,
  280. RefStart might end up below HighHeap, and the final message would
  281. indicate that more heap    space was used than was    available.  This is
  282. not an error - only if RefStart    hits HeapLim will an error be reported.
  283.  
  284.  
  285.      The secondary heap    is also    built from both    ends, but it grows and
  286. shrinks    according to how many macros and include files are currently open.
  287. At all times there will    be at least one    entry on the heap, for the original
  288. source code file.
  289.      The bottom    of the heap holds the names of the source code file and
  290. any macro or include files that    are currently open.  The full path is
  291. given.    A null string is stored    for user macros.  Macro    arguments are
  292. stored by additional strings, one for each argument in the macro call line.
  293. All strings are    stored in minimum space, similar to the    labels and user
  294. macro text on the primary heap.     File names are    pointed    to by the fixed
  295. table entries (see below) - macro arguments are    accessed by stepping past
  296. the macro name to the desired argument,    unless NARG would be exceeded.
  297.      The fixed portion of the heap is built down from the top.    Each entry
  298. occupies 16 bytes.  Enough information is stored to return to the proper
  299. position in the    outer file once    the current macro or include file has been
  300. completely processed.
  301.      The diagram below illustrates the layout of the secondary heap.
  302.  
  303.     Heap2 +    maxheap2 ----------->  ___________________________
  304.                       |                  |
  305.                       |      Input    file table      |
  306.     struct InFCtl *InF ---------> |___________________________|
  307.                       |                  |
  308.                       |      Parser operator stack      |
  309.     struct OpStack *Ops --------> |___________________________|
  310.                       |                  |
  311.                       |      (unused space)      |
  312.     struct TermStack *Term -----> |___________________________|
  313.                       |                  |
  314.                       |      Parser term stack      |
  315.     char *NextFNS --------------> |___________________________|
  316.                       |                  |
  317.                       |      Input    file name stack      |
  318.     char *Heap2 ----------------> |___________________________|
  319.  
  320.      The "high-water mark" for NextFNS is stored in char *High2,
  321. and the    "low-water mark" (to stretch a metaphor) for InF is stored
  322. in struct InFCtl *LowInF.  Again, these    figures    are used only to
  323. determine the maximum heap usage.
  324.  
  325.  
  326.      Please send me any    bug reports, flames, etc.  I can be reached on
  327. Dorean BBS (604/432-8579), Mind    Link (604/533-2312), at    any Panorama
  328. (PAcific NORthwest AMiga Association) meeting, or via Jeff Lydiatt
  329. or Larry Phillips.  (I don't have the time or money to live on
  330. Usenet or CompuServe, etc.)
  331.  
  332.                 Charlie    Gibbs
  333.                 #21 - 21555 Dewdney Trunk Road
  334.                 Maple Ridge, B.C.  CANADA
  335.                 V2X 3G6
  336.  
  337.  
  338. P.S.  I    plan to    add 68010/68020    support    in the future.    Stay tuned.
  339.